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MODULE Lpmultast(ZTITLE* Line printer driver’ MAIN=lp_main, IDENT='V04-000')= 
i 
i eeeerereereerererererererererereenerereeeteeeeereneeeeerererererrerereeetete 


ie COPYRIGHT (c) 1978, 1980, 1982, 1984 


. BY * 
ie DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS. . 
: ALL RIGHTS RESERVED. ~ 
ie THIS SOFTWARE Is uf PRNTSHED UNDER A LICENSE AND MAY BE USED AND COPIED . 
ie ONLY IN ACCORDA NCE WITH THE TERMS OF SUCH LICENSE AND Ae THE 2 
ie INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOF TWA RE OR * 
ie COPIES THER EOF MAY hor BE PROVIDED OR OTHERWISE MADE AVAILABLE 1). ANY . 
ie OTH TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY * 
te PRANSFERRED . 
ie THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTIC : * 
ie AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 
‘+ CORPORATION. . 
ie DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS * 
ie SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. ‘ 
'@ 
! 
aap ie tiniseiibtbie atenahiasiatinenitiGaniammmdaaaemsieimmbensmauimmnddiinanibieedcnin 


' 

i 

‘ee 

i FACILITY: 


A sample program that illustrates the use of the connect to 
interrupt facility. 


i ABSTRACT: 
i This program assigns a channel to a line printer device, and 
then connects to the dostes via the connect to interrupt 


' 

' 

' 

' 

J 

' 

' 

' 

' 

' 

: facility. The program then requests the name of a file from 
} the user, and outputs that file on the Line printer. 
' 
‘ 
' 
' 
' 
' 
' 
' 
' 


Alan Lehotsky 12-Oct-1979 
i REVISION HISTORY: 
i Revised for publication APL 21-Mar-1980 


Siac siete sige cicadas idavnagn xisaaicersaateaicedeliedaonclsea i daadinsdte tone iia caapiannssnieniactelibacsinmsicaiesiioees toe 
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ZSBITL ‘External and local symbol definitions’ 
BEGIN 


LIBRARY ‘SYSSLIBRARY:LIB'; ! Get important definitions 
PSECT 

; Define some PSECTs which we will need to refer to Later 

OWN= sharedata(ALIGN(9) ,WRITE), 

OWN= data; 
LINKAGE 


intrupt=  JSB(REGISTER=2 REG! TER=4, REGISTER=S): 
sien 1,2,3,4) NOTUSED(6,7 10,1 
cancel= JSB(REGISTER= 5 megigtenes, REGISTER=4, REG ESTER o6) 


FORWARD ROUTINE 


lp_interrupt intrupt PSECT(sharedata), ! Interrupt server 
Lp. saqeess NOVALUE cancel PSECT(sharedata), ! Cancel 1/0 
P_main, 

ip_isr ast, 

lp ~ iodone ast; 


' 
Static Definitions 


LITERAL 
true = > 
false = 0. 
io_page_count = 1, ! Pages needed in UNIBUS 1/0 space 
jio_space_base = %x'20100000', ! Physical eddress of UBA 0 space 
! for VAX=-11/780. Other processers 
! need different magic number... 
unibus_lp_addr= %0°777514', ! 18-bit addr of LP11 CSR 


i Celculate the pegerens number to map to get the physical address 
i that the unibus mapped on. 


ie pees bits = (io space_base + unibus_(p_addr)/512, 
ip_csr_offset = unibus_lp_addr and 511, ! Offset to printer CSRs. 
filename_length = 100, 


record _bufsiz = $36 
prompt_length = 8; 


| wef 
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OWN 
ipchan: WORD, 
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! Line printer channel number. 


filename _buffer: VECTONE 1 Lonane Length, BYTE] 

file_descr: VECTORE2) INITIAL( Filename_length, filename_buffer), 
fdlen: WORD, 

record_buffer: VECTORCrecord_bufsiz,BYTE), 


file_fab: $fab( 
joceort. 
fna=Tilename_buffer, 
org=seq, 


rfm=var 
dnm='TEST.LIS"), 


file_rab: S$rab( 
fab=file_fab, 
rac=seq, 
ubf=record_buffer 
usz=record_bufsiz), 


io_page_limits: VECTOR(2) 
INITIAL ( OO. 


BIND 
onesecond_delta= 
UPLITT-10#1000*1000,-1); 


! Input file fab 


Addresses of ag By 
UNIBUS 1/0 page. 200 tells SCRMPSC 
to map pages in PO space 


Delta time format for one 


! second. 


+ 
! Define offsets into the buffer that will be shared by the user 
process and the process routines that execute in kernel mode. 


FIELD 

buf= 
$l_f = Ve . 
bot$er ints tS: 3269. 


$t-crarcountsts 8-36-03. 


f 
f 
$s 


lp_csr= -0.16,1), 
Lpedbr= 3:88) 


lp= 


Flags longword. 
Interrupt expected 


Number of chars in buffer 
Start of data in buffer. 


Offset to Line printer CSR 
Offset to Line printer data 


e@eee 
eeeeeeeeeseeeeeeeeeeee® 


+ 
+ 


n 
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ZSBTTL ‘Double Mapped Page Buffers’ 


output _buffer: BLOCK(512,BYTE) FIELD(buf) PSECT(sharedata); 
PSECT 
= sharedata, 
PLIT= sharedata; 


The routines to be executed in kernel mode must follow directly 
after this allocation of bytes to hold output data. 


— 
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ZSBTTL ‘“LP_INTERRUPT, Interrupt service routine’ 
ROUTINE ip_interrupt( arglist, idb, ucb ): intrupt PSECT(sharedata)= 
i‘ Functional description: 


This routine services an interrupt from the Line printer 
device. If the interrupt was expected, the routine disables 
output interrupts. The disable is an optimization to prevent one 
interrupt per character. With output interrupts disabled, the 
Line printer buffers characters until the device needs to output 
the characters. Then the main program enables qutqut interrupts 
tA the period of time necessary for the device to empty 

e buffer. 


Then the interrupt service routine loads a success status into 
RO and returns. 


If the interrupt was not expected, the routine just loads 
an error status into RO to prevent delivery of an AST to the 
owning process and returns. 


Inputs: 
R2 - address of a counted argument List 
RG - address of the IDB 
RS - address of the UCB 


The counted argument List is as follows: 
count of arguments (4) | 


O(R2) = 
4(R2) = the system-mapped address of the user buffer 
8(Re) = the system-mapped address of the device's CSR 
12(R2) = the IDB address 
16(R2) = the UCB address | 
Outputs: : 
The routine must preserve all registers except RO-R4. 
BEGIN 
MAP 
arglist: REF VECTORC,LONG), 
ucb: REF BLOCK BYTE), 
o_o REF BLOCK(,BYTEJ; 
bufadr = arglist(1): REF BLOCK FIELD(buf); ! System adr of buffer 
BUILTIN 
TESTBITCC; 
VESTBITCES bufadr(buf$l_fiags] ) 
RETURN 0; ! No interrupt expected, no AST wanted 
(.idbCidb$l_csrJ)<0,16> = 0; ! Disable the output interrupt 
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ZSBTTL ‘LP_CANCEL, Cancel 1/0 on Line Printer’ 

ROUTINE lp_cancel( chan_idx, irp, pcb, ucb ): NOVALUE cancel PSECT(sharedata)= 
Functional description: 

This routine disables output interrupts from the Line printer. 

Inputs: 

Re = negated value of the channel index number 

R - address of the current IRP (1/0 request oacket) 

RG address of the PCB (process control block) ‘or the 


process canceling I/ 
address of the UCB (unit control block) 


RS 
Outputs: 


none 
BEGIN 
AP 
irp: REF BLOCK(,BYTE), 
pcb: REF BLOCK(,BYTE), 
ucb: REF BLOCK( BYTEJ; 
BIND 
crb= -ucbCucb$t_crb]: BLOCKC BYTE); 
LOCAL 
csr: REF BLOCKC, BYTE) FIELD(\p); ! UNIBUS addr. 
csr = ..(crbd{crb$l_intd] + BLOCK(LO, vec$l_idb;0,BYTE)); ' Addr of CSR 


gorClp.cerd = 0 ! Disable output interrupts. 


~~ ee 


P 
P 
Pp 
P 
) 
P 


annnun 
ah 


CUE WN— 


Oo eee rr O_O OO Ose - 
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ZSBTTL LP_MAIN, the main routine’ 

ROUT INE Lp_main: PSECT(SCODES)= 

‘tp MAIN, the routine that controls the others 
i Functional description: 


1. Assign a channel to the Line printer. 
¢: Map the process to the 1/0 p a 
- Issue @ connect to mater 10 to get the Line printer. 
4. Prompt the user for a file n 
5. Open and connect to the file. 
6. Write the contents of the file to the Line printer. 


i Inputs: 
none 
i Qutputs: 
RO = status code 
SS$_NORMAL - success 
RMS code - error be opening or reading 
he | 
SS$_DEVOFFLINE <= error is writing to printer 
BEGIN 
PSECT 
OWN= SOWNS; 
buffer_desc: VECTORC2) INITIAL( ! Descriptor of buffer shared 
512+51 ! by process and kernel mode 
output_ buffer), ! process routines. 


' List of offsets to kernel 

! mode routines: init device; | 
i start device; 
i snterrupy servicing; 
i cancel 


entry_List: YECTORL4] INITIAL ( 


Lp_ interrupt-output_buffer, 
lp_cancel-output_buf fer); 


csr: REF BLOCKC BYTE) FIELD(Lp) VOLATILE, 
status; 


EXTERNAL ROUTINE 
Lib$get_input; 
' 
! Assign a channel to the Lire printer. 


status = Sassign( ' Assign channel to Line 
devnam=S$DESCRIPTOR("LPAO'), i printer 
chan=|pchan); 


——————__—_—__—— 
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If NOT .status THEN RETURN .status; 


i Map the UNIBUS 1/0 page to the process so that the Line printer's 
: device registers are accessible. 


status = Scrmpsc ( ! Map 1/0 page to process. 
inadr=io_page_limits, 
retadr=io_page Limits, 
flags=secSm_wrt OR secSm_pfnmap OR sec$m_expreg, 
pagcnt=io_page_count, 
vbn=io_page_pfn ); 


1F NOT .status THEN RETURN .status; 
Issue a connect to interrupt Q10 to the Line printer device. This 


| 
| 
connection will allow the program to control and handle interrupts 
from the device. | 


status = $qio( ! Connect the process to the 
chan=.lpchan ' Line printer device. 
func=io _conintread, ! Specify a read only buffer. 
astadr=|p_iodone_ast, ! Specify an AST routine. 
pi=buffer_desc, ' Specify a shared buffer. 


pe=entry_Tist, — ! spec ty routine entry points. 
p3=cin$m_isr OR cin$m_cancel, ; 

! Specify ISR, cancel routines. 
pi=lp_israst, i Specify an interrupt AST. | 
p6=5); ! Specify an AST count. 


IF NOT .status THEN RETURN .status; | 
Ask user what file to print. 


status = Lib$get_input( file_descr, : f | 
$descriptor('Name of file to be printed: '), 
file_descr(0]); 


IF NOT .status THEN RETURN .status; 


Open and connect file. 


file fab(fab$b_fns] = .file_descr(0); ! Length of spec. 
status = Sopen(fab=file_fab); ! Open file. 
If NOT .status THEN RETURN .status; 
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status = Sconnect( rab = file_rab ); ! Connect file. 
If NOT .status THEN RETURN .status; 


| 
ND 
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! 
' Get a record at a time until end of file. Surround record's contents 
: with a Linefeed and a carriage return. 


WHILE status = S$get(rab=file_rab) DO 
BEGIN 
LOCAL 
np. 
outp; 


outp = output buffer(buf$l_startdata]; |! Target for first character 
CHSWCHAR_A( ZCHAR(ZX'A'), Sutp); ! Start with a line-feed 


inp = record_buffer; 


' Load Length of this output buffer in the buffer header. Then copy 
' the contents of the input buffer to the output buffer. Translate all 
: lower case alphabetics to upper case characters. 


output_buffer(bufSw_charcount) = .file_rabCrab$w_rsz] + 2; 
DECR i FROM .file_rabCrab$w_rszJ-1 TO 0 DO 
BEGIN 


LOCAL 
char; 


char = CHSRCHAR_A( inp ); 
SELECTONE .char OF 


SET 
ore © TO %£C°2z'): char = .char - %X'20'; ! Upcase 


CHSWCHAR_A( .char, outp ) 
ENU; 


CHSWCHAR_A( ZCHAR(ZX'0D'), outp ); ! Put CR at end. 


Send characters one at a time to the Line fy Before sending a 
character, see if the Line printer is still in ready state. If not, 
set a timer to go off in one second, and go to sleep. When an AST 
occurs -- either because of a line printer interrupt, or because. 
the timer runs out, the AST routine will wake the process up again. 


If the Line printer is still in ready state, just send the next 
character. 


outp = output_buffer(buf$l_startdata); |! Addr of output string 
csr = .io_page_limits + lp_csr_offset; ! Addr of LP's CSR 


ADD 
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WH 


BIND 
devbits= csr{lp_csrJ: VOLATILE SIGNED WORD; 


mes | eubeeneadiens FROM -1 TO 1 OF 
{-1]: RETURN ss$_devoffline; ! Paper problem, maybe 
(1): 


DECR i FROM .output_bufferlbuf$Sw_charcountJ-1 TO 0 DO 
- pO 


ae ' Output a character 
csr Lp dbr] = CHSRCHAR_A( outp ; 
EXITLOOP ' Back for next char 


(0): '¢ 
! Line printer is not ready. See whether it's in 
! trouble, or just busy. If it's in trouble, stop 
! program with error status. Otherwise, just wait 
! until it comes ready again. 


BEGIN 
output_buffer(Cbuf$v_int] = true; ! Interrupt expected 
csr(lp_csr) = .csr{Tp_csr] OR %x'40'; : Enable LP interrupts 


status = $setimr( Set a one second timer. 


daytim=onesecond delta, 
astadr=lp_isr_ast); 
IF NOT .status THEN RETURN .status; 


$hiber; ! Go to sleep. 
peeee ees ! Cancel timer request 


TES 
END 
END; ! End $SGET loop 
4 -Status NEQ ss$_endoffile 


RETURN .status; 


$close( fab=file_fab ) 
END, 
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ZSBTTL ‘"LP_ISR_AST = AST routine to respond to interrupt’ 
ROUTINE lp_isr_ast= 
LP_ISR_AST, AST routine to handle an expected Line printer interrupt 
! Functional description: 
i This AST routine gains control when the Line printer generates 
: an interrupt that the process expects. The interrupt usually 
: indicates that the Line printer has finished emptying its data 
buffers, and is ready to accept more input. 
Since the process is hibernating, wake the process so that it 
can check Line printer status, and continue outputting the 
data record. 
Inputs: 
4 (AP) = an AST parameter (unused) 
Outputs: 
none 
The routine preserves all registers. 
Implicit outputs: 


The sleeping process awakes. 


Swake(); ! Wake the sleeping process. 


ane | 


S 
° 


+ 
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ZSBTTL ‘LP_IODONE_AST = AST routine at Q10-completion’ 

ROUTINE lp_iodone_ast= 

i LP_IODONE_AST, An AST routine for O10 compietion 

Functional description: 

This AST routine gains control when the connect to interrupt 

Q10 request completes. This only occurs if VMS decides to 

disconnect the process from the interrupt in order to cancel 

1/0 - the channel during process rundown. The action of the 

routine is to exit with a status indicating that the 1/0 

was cancelled. 

! Inputs: | 
none 

' Outputs: | 

none | 


The routine preserves all registers. 


$Sexit( CODE=ss$_abort ); 


END ELUDOM 


VAX/VMS V4.0 
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